<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>MsgBox</title>
<meta name="description" content="Display MsgBox windows easily in this free scripting language. You can also create custom data entry forms, user interfaces, and menu bars.">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>MsgBox</h1>

<p>Displays the specified text in a small window containing one or more buttons (such as Yes and No).</p>

<pre class="Syntax">MsgBox, Text
MsgBox [, Options, Title, Text, Timeout]</pre>
<h3>Parameters</h3>
<dl>

  <dt>Text</dt>
  <dd><p>If all the parameters are omitted, the MsgBox will display the text &quot;Press OK to continue.&quot;. Otherwise, this parameter is the text displayed inside the message box to instruct the user what to do, or to present information.</p>
    <p><a href="_EscapeChar.htm">Escape sequences</a> can be used to denote special characters. For example, `n indicates a linefeed character, which ends the current line and begins a new one. Thus, using text1`n`ntext2 would create a blank line between text1 and text2.</p>
    <p>If <em>Text</em> is long, it can be broken up into several shorter lines by means of a <a href="../Scripts.htm#continuation">continuation section</a>, which might improve readability and maintainability.</p></dd>

  <dt>Options</dt>
  <dd><p>Indicates the type of message box and the possible button combinations. If blank or omitted, it defaults to 0. See the table below for allowed values.</p>
    <p>This parameter must be either a literal number or (in v1.1.06+) a forced expression such as <code>% Options</code>. Any other non-blank value will not be recognized as this parameter, but instead as part of <em>Text</em> in the single-parameter mode.</p></dd>

  <dt>Title</dt>
  <dd><p>The title of the message box window. If omitted or blank, it defaults to the name of the script (without path).</p></dd>

  <dt>Timeout</dt>
  <dd><p><a name="Timeout"></a>(optional) Timeout in seconds, which can contain a decimal point but is not an expression by default. In v1.1.06+, this can be a forced expression such as <code>% mins*60</code>.</p>
    <p>If this value exceeds 2147483 (24.8 days), it will be set to 2147483. After the timeout has elapsed the message box will be automatically closed and the <a href="IfMsgBox.htm">IfMsgBox</a> command will see the value TIMEOUT.</p>
      <p>Known limitation: If the MsgBox contains only an OK button, <a href="IfMsgBox.htm">IfMsgBox</a> will think that the OK button was pressed if the MsgBox times out while its own <a href="../misc/Threads.htm">thread</a> is interrupted by another.</p></dd>

</dl>

<p>The <em>Options</em> parameter can be a combination (sum) of one or more of the following values.</p>
<table class="info" style="width:55%">
  <tr>
    <th width="287">Function</th>
    <th>Decimal Value</th>
    <th>Hex Value</th>
  </tr>
  <tr>
    <td>OK (that is, only an OK button is displayed)</td>
    <td align="center">0</td>
    <td align="center">0x0</td>
  </tr>
  <tr>
    <td>OK/Cancel</td>
    <td align="center">1</td>
    <td align="center">0x1</td>
  </tr>
  <tr>
    <td>Abort/Retry/Ignore</td>
    <td align="center">2</td>
    <td align="center">0x2</td>
  </tr>
  <tr>
    <td>Yes/No/Cancel</td>
    <td align="center">3</td>
    <td align="center">0x3</td>
  </tr>
  <tr>
    <td>Yes/No</td>
    <td align="center">4</td>
    <td align="center">0x4</td>
  </tr>
  <tr>
    <td>Retry/Cancel</td>
    <td align="center">5</td>
    <td align="center">0x5</td>
  </tr>
  <tr>
    <td>Cancel/Try Again/Continue</td>
    <td align="center">6</td>
    <td align="center">0x6</td>
  </tr>
  <tr>
    <td>Adds a Help button (see remarks below)</td>
    <td align="center">16384</td>
    <td align="center">0x4000</td>
  </tr>
  <tr>
    <td>&nbsp;</td>
    <td align="center">&nbsp;</td>
    <td align="center">&nbsp;</td>
  </tr>
  <tr>
    <td>Icon Hand (stop/error)</td>
    <td align="center">16</td>
    <td align="center">0x10</td>
  </tr>
  <tr>
    <td>Icon Question</td>
    <td align="center">32</td>
    <td align="center">0x20</td>
  </tr>
  <tr>
    <td>Icon Exclamation</td>
    <td align="center">48</td>
    <td align="center">0x30</td>
  </tr>
  <tr>
    <td>Icon Asterisk (info)</td>
    <td align="center">64</td>
    <td align="center">0x40</td>
  </tr>
  <tr>
    <td>&nbsp;</td>
    <td align="center">&nbsp;</td>
    <td align="center">&nbsp;</td>
  </tr>
  <tr>
    <td>Makes the 2nd button the default</td>
    <td align="center">256</td>
    <td align="center">0x100</td>
  </tr>
  <tr>
    <td>Makes the 3rd button the default</td>
    <td align="center">512</td>
    <td align="center">0x200</td>
  </tr>
  <tr>
    <td>&nbsp;</td>
    <td align="center">&nbsp;</td>
    <td align="center">&nbsp;</td>
  </tr>
  <tr>
    <td>System Modal (always on top)</td>
    <td align="center">4096</td>
    <td align="center">0x1000</td>
  </tr>
  <tr>
    <td>Task Modal</td>
    <td align="center">8192</td>
    <td align="center">0x2000</td>
  </tr>
  <tr>
    <td>Always-on-top (style WS_EX_TOPMOST)<br>
      (like System Modal but omits title bar icon)</td>
    <td align="center">262144</td>
    <td align="center">0x40000</td>
  </tr>
  <tr>
    <td>&nbsp;</td>
    <td align="center">&nbsp;</td>
    <td align="center">&nbsp;</td>
  </tr>
  <tr>
    <td>Make the text right-justified</td>
    <td align="center">524288</td>
    <td align="center">0x80000</td>
  </tr>
  <tr>
    <td>Right-to-left reading order for Hebrew/Arabic</td>
    <td align="center">1048576</td>
    <td align="center">0x100000</td>
  </tr>
</table>
<h3>Remarks</h3>
<p>The table above is used by adding up the values you wish to be present in the MsgBox. For example, to specify a Yes/No box with the default button being No instead of Yes, the <em>Options</em> value would be 256+4 (260). In hex, it would be 0x100+0x4 (0x104).</p>
<p>MsgBox has smart comma handling, so it is usually not necessary to <a href="_EscapeChar.htm">escape</a> commas in the <em>Text</em> parameter.</p>
<p>To determine which button the user pressed in the most recent MsgBox, use the <a href="IfMsgBox.htm">IfMsgBox</a> command. For example:</p>
<pre>MsgBox, 4,, Would you like to continue? (press Yes or No)
IfMsgBox Yes
    MsgBox You pressed Yes.
else
    MsgBox You pressed No.</pre>
<p>The names of the buttons can be customized by following <a href="../scripts/MsgBoxButtonNames.htm">this example</a>.</p>
<p><strong>Tip</strong>: Pressing Control-C while a MsgBox window is active will copy its text to the clipboard. This applies to all MsgBoxes, not just those produced by AutoHotkey.</p>
<p><strong>Using MsgBox with GUI windows</strong>: A GUI window may display a <em>modal</em> MsgBox by means of <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a>. A <em>modal</em> MsgBox prevents the user from interacting with the GUI window until the MsgBox is dismissed. In such a case, it is not necessary to specify the System Modal or Task Modal options from the table above.</p>
<p>When <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a> is <em>not</em> in effect, the Task Modal option (8192) can be used to disable all the script's windows until the user dismisses the MsgBox.</p>
<p><strong>The Help button</strong>: When the Help button option (83) is present in <em>Options</em>, pressing the Help button will have no effect unless both of the following are true:</p>
<ol>
  <li>The MsgBox is owned by a GUI window by means of <a href="Gui.htm#OwnDialogs">Gui +OwnDialogs</a>.</li>
  <li>The script is monitoring the WM_HELP message (0x53). For example: <code><a href="OnMessage.htm">OnMessage(0x53, &quot;WM_HELP&quot;)</a></code>. When the WM_HELP() function is called, it may guide the user by means such as showing another window or MsgBox.</li>
</ol>
<p><strong>The Close button (in MsgBox's title bar)</strong>: Since the MsgBox window is a built-in feature of the operating system, its <strong>X</strong> button is enabled only when certain buttons are present. If there is only an OK button, clicking the <strong>X</strong> button is the same as pressing OK. Otherwise, the X button is disabled unless there is a Cancel button, in which case clicking the <strong>X</strong> is the same as pressing Cancel.</p>
<h3>Related</h3>
<p><a href="IfMsgBox.htm">IfMsgBox</a>, <a href="InputBox.htm">InputBox</a>, <a href="FileSelectFile.htm">FileSelectFile</a>, <a href="FileSelectFolder.htm">FileSelectFolder</a>, <a href="ToolTip.htm">ToolTip</a>, <a href="Gui.htm">GUI</a></p>
<h3>Example</h3>
<pre class="NoIndent">MsgBox This is the 1-parameter method. Commas (,) do not need to be escaped.
MsgBox, 4, , This is the 3-parameter method. Commas (,) do not need to be escaped.
MsgBox, 4, , Do you want to continue? (Press YES or NO)
IfMsgBox No
    return
MsgBox, 4, , 4-parameter method: this MsgBox will time out in 5 seconds.  Continue?, 5
IfMsgBox Timeout
    MsgBox You didn't press YES or NO within the 5-second period.
else IfMsgBox No
    return
    
<em>; By preceding any parameter with &quot;% &quot;, it becomes an <a href="../Variables.htm#Expressions">expression</a>. In the following example,
; math is performed, a <a href="../misc/Arrays.htm#pseudo">pseudo-array</a> element is accessed, and a function is called.  All these
; items are concatenated via the &quot;.&quot; operator to form a single string displayed by MsgBox:</em>
MsgBox % &quot;New width for object #&quot; . A_Index . &quot; is: &quot; . RestrictWidth(ObjectWidth%A_Index% * ScalingFactor)

<em>; The following example alerts the user that a MsgBox is going to steal focus (in case the user is typing).</em>
SplashTextOn,,, A MsgBox is about to appear.
Sleep 3000
SplashTextOff
MsgBox The backup process has completed.</pre>

</body>
</html>
